Repository navigation
spec(FIX-1788): amend after merge · a session is bound through its readonly starting state; custom-flow privacy is the author's - #2857
Conversation
…tate; custom-flow privacy is the author's Records three directions the product owner approved on 2026-10-07: - D5: a session holds its worker in a readonly field of its starting state (`workerId`), checked at create by the optional create check and listed by the store-level state filter. No separate link, and no `worker` option on createSession/listSessions. Supersedes D4's mechanism; D4's call stands. - D6, formerly Q6, answered A: on a custom worker flow, keeping one user's workers apart is the flow's author's job. BR-23 and S7 narrow to the built-in worker flows; BR-23a and a DOCS.md section added. - The three engine changes P1 shipped beyond the epic's D3 item (3): a readonly guard, a store-level listing filter, and a create-time schema refusal on flows that bind their sessions. Original review: #2812. Amends the retained set only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
…ed skills, adoption refusal, FIX-1797 control name - S7, D6, EVOLUTION, DOCS: P2 (7c765ab) removed agent's state-read partitionBy; the per-worker drawer lands in P4 through the installation's session. A partitioned skills library fails closed: a run with no partition gets an empty view whose writes are refused. - BR-18b, S11, V4, the guardrail, At implement time, EVOLUTION: P4 makes the engine refuse to adopt an existing child whose readonly fields differ from the requested state, and keys the mailbox wake's child by worker too. - FIX-1797 PLAN P3.3: the FIX-1788 goal control is renamed caller-link -> no-create-check, a consequence of this amendment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
There was a problem hiding this comment.
Problem
After P1 (#2850), the issue spec still described a server-only session “link” and overstated per-worker privacy on every worker flow. This amend has to catch up to shipped binding primitives and record the PO answer on custom-flow privacy (Q6 → D6).
Verdict
Approve for direction. Readonly workerId in session starting state is the right reconciliation with P1 and with the generic “binds its sessions” pattern in state-and-scopes. D6 correctly narrows BR-23 to built-ins and points custom flows at ER-2 + author keying (aligned with FIX-1789’s declaration limits). BR-18b and the no-create-check goal control rename are real gaps the old link model did not cover.
The mechanism choice is not where complexity crept in — spec surface area did: the same story is told in several parallel places, which will drift and makes implementers read S1 twice.
Simpler shape (optional editorial pass, not blocking)
-
D4 vs D5 — One product fork (“named once at create”). D5 is a mechanism amend to D4 after P1, not a second decision fork. Consider folding D5 into D4 as an “Amended mechanism” subsection (or demote D5 to
EVOLUTION.mdonly) and drop theD4 → D5tree edge + one figure pair. SPEC sign-off could stay at two bullets (timing + storage) without two full decision cards. -
Single home for “three engine changes beyond epic D3(3)” — Today: D5 Locks in,
EVOLUTION.md#amendment-binding, SPEC sign-off §4, PLAN guardrails. Pick one canonical paragraph; elsewhere one-line pointers. -
S1 overload — The S1 table cell is now the whole binding textbook (birth paths, readonly guard, binding vs non-binding flows, listing, dispatch,
fsdev run, React). Reusedocs/architecture/state-and-scopes.md+ the user “one session per project” example as mechanism authority; keep FIX-1788-specific:workerId, Workforce create check, S5a criteria, BR-10–19c. -
D6 thickness — Policy is already epic ER-2; FIX-1789 two-shapes POC is the right “why not refuse at hire.” A thinner D6 (or BR-23a + DOCS only, with D6 as a short EVOLUTION row) would match how much is new vs documented.
-
BR-18b — Necessary rule; narrated in BR, PLAN S11/V4, and EVOLUTION. BR + PLAN is enough; EVOLUTION can index without re-deriving
evaluateAdoption. -
Terminology — Residual “link” / “binding” alongside
workerIdand criteriaworkerwill confuse readers against stale epic ER-1/D3(3) text. EVOLUTION already defers epic amend; a one-line glossary in PLAN pinned-names (“link = pre-D5 server-only field”) would help until epic mirror lands.
Implementation watch (spec-implementer, not this PR)
S5a / BR-14a key-set matching vs store listSessions({ state }) (positive equality on named readonly fields only): Workforce must own “criteria key not named ⇒ session must not carry that key,” not assume SQL does it. Risk: over-fetch, wrong “most recent” session, or unbounded paging on busy workers. Prefer pushing full criteria into state when known; document bounded scan for partial { worker } only. BR-18b should compare readonly keys in the dispatch payload, not deep-equal full state.
Cross-spec
Good: DOCS “Published with P1” defers to shipped pages; FIX-1797 no-create-check sync. Follow-up (separate PR): epic ER-1 / D3(3) “server-only link” and FIX-1789 D1 worker source wording.
Minor
- SPEC feature line still lists
react; S1 saysuseFlowunchanged — align or note docs-only React path. - V6 no longer proves custom-flow per-worker isolation (BR-23a via docs example) — intentional with D6; worth one explicit “we accept weaker automated proof here” line if reviewers ask.
No changeset needed (spec-only).
Sent by Cursor Automation: Review For Best Approach
| D3 -.->|"rejected · an edit to the files changes your fork"| X3["a fork follows them"] | ||
| I --> D4["D4 · a session's worker is named at create"] | ||
| D4 -.->|"rejected · every message carries the worker"| X4["named on the first turn"] | ||
| D4 --> D5["D5 · named in a readonly field of the session's starting state"] |
There was a problem hiding this comment.
Simplify (optional): D4 → D5 reads like a second product decision. In practice D5 is “D4’s storage mechanism, amended after P1.” Folding mechanism into D4 (or keeping D5 only in EVOLUTION.md) would shrink the decision tree and two overlapping SVGs without changing what implementers build.
| | ID | Package · role | Change | Rules | | ||
| |---|---|---|---| | ||
| | S1 | `engine` + `core` + `client` + `react` · server-owned session data, at create | One declaration, two parts, behind **one session-birth function**. **Birth:** it owns the stale-state purge, the flow's create check and the insert-if-absent write. `handleCreateSession`, `ensureSessionRecord` and the dispatched-child writer become thin callers, so every `SessionRecord` insert goes through it by construction. There are five paths today: the create route, an action's write for a missing session id (`createExecutionContext`), the webhook session resolver, `fsdev run` (`packages/cli/src/commands/run.ts`, through the exported `ensureSessionRecord`), and a task dispatched to another flow (`engine/src/context/create-request-host.ts`, which writes the child record before the target's task entry runs, so it carries the worker from the dispatching flow's code into the birth). Each caller keeps its choice over a lost race: the route answers 409, and the action and dispatch paths adopt the winner's record without re-checking the loser's input, as intended. **A create field:** the check gets the verified principal and the create's input. It refuses, or returns a value the engine stores under a generic key on the record, outside `state`. No route writes the field afterwards. A birth with no input is refused. The async check runs on a miss only, never on a turn of an existing session. **Server-written state:** session-state fields the birth refuses from a caller (400, naming the field) and only flow code writes. They ship here because epic D3 *Locks in* (3) has FIX-1788 build the mechanism and FIX-1791 consume it, and the refusal must exist before any app can seed those fields. FIX-1791's delegates ([#2815](https://github.com/fixpoint-labs/flow-state-dev/pull/2815)) are the consumer; BR-18a and V4 drive it until FIX-1791's goal covers it. The list route filters on the create field. `fsdev run` takes `--worker <id>` for a new session on a worker flow, and refuses a new one without it; `--seed-session` refuses server-written fields. The client's `createSession` takes `worker` and `listSessions` a `worker` filter, mapped onto that field; `useFlow` passes `worker` to both. The engine knows no worker. Undeclared means today | BR-13 BR-14 BR-15 BR-16 BR-18a | | ||
| | S1 | `engine` + `core` + `client` · binding a session at create (shipped in P1, [#2850](https://github.com/fixpoint-labs/flow-state-dev/pull/2850)) | **One session-birth function** every `SessionRecord` insert goes through: the create route, an action's write for a missing session id (`createExecutionContext`), the webhook session resolver, `fsdev run`, and a task dispatched to another flow (`engine/src/context/create-request-host.ts`). It owns the stale-state purge, the checks below and the insert-if-absent write; it runs on a miss only, never on a turn of an existing session. Each caller keeps its choice over a lost race: the route answers 409, and the action and dispatch paths adopt the winner's record without re-checking the loser's input. **What a flow declares on `session`** ([D5](DECISIONS.md#d5)): *a readonly field*, a top-level `.readonly()` field of `stateSchema`, set from the create's starting `state` and refused on any later change by every path that writes session state (a block, a tool, an action, `fsdev run --seed-session` on an existing session); *`createCheck`*, optional, which gets the starting state as the schema parsed it, the verified caller and a read of one collection row at the caller's own scope, and accepts or refuses, for a rule that depends on the caller or the store; *`serverOwned`*, state fields a caller's create may not seed (400, naming the field) and only flow code writes. `serverOwned` ships here because epic D3 *Locks in* (3) has FIX-1788 build the mechanism and FIX-1791 consume it; FIX-1791's delegates ([#2815](https://github.com/fixpoint-labs/flow-state-dev/pull/2815)) are the consumer, and BR-18a and V4 drive it until FIX-1791's goal covers it. **A flow binds its sessions** when it declares a readonly field or a create check: its create refuses a starting state its schema rejects (400, naming the field). Every other flow keeps today's create, which stores a failing state as sent ([DECISIONS.md](DECISIONS.md#decided-not-asked)). **Listing:** `listSessions({ state })` and the route's `?state.<field>=` filter on readonly fields only, by exact string match, inside the store's query; any other field is refused with 400. **Dispatch:** a dispatcher's `session: { key, state }` and a task dispatcher's `state` give a child session its starting state, from the dispatching flow's code. `fsdev run` names the worker through `--seed-session`, and a new session on a binding flow without it is refused. `useFlow` is unchanged: it sends no starting state, so on a binding flow an app creates the session through the client and selects it. The engine knows no worker. Undeclared means today | BR-13 BR-14 BR-15 BR-16 BR-18a | |
There was a problem hiding this comment.
Density / reuse: This cell now duplicates much of docs/architecture/state-and-scopes.md (birth, readonly, binding vs non-binding, listing). Consider an index row here + pointers to architecture/user docs for generic mechanism, reserving this spec for Workforce-specific deltas (workerId, create check, S5a, BR ids). Easier to maintain after the next engine tweak.
| | S7 | `orchestration` + `workforce` · private state by worker | The skills library takes its key per run: a function of the running context that the composing layer supplies, the shape of epic D6's partition, naming no worker. Workforce supplies the worker. Every flow-isolated resource on a worker flow is keyed by the worker. The `agent` drawer first. The library's half is a Layer 1 mechanism change, the sixth the epic's D3 counts | BR-23 BR-25 | | ||
| | S5 | `workforce` · the worker's create check, one module | Every worker flow declares a readonly `workerId` on its session `stateSchema` and this create check through S1: a worker is named; it is the principal's own (read at their scope) or a standard one; it names this flow; a derived worker-session id is the caller's. It accepts or refuses; the worker is the session's `workerId`. The id derivation is one exported function, used by both this check and `ensureWorkerSession`, and it runs on the tenant-resolved key. The task entry and the mailbox wake open sessions through it, naming the worker in the child's starting state from the dispatching flow's code. No turn changes `workerId`: S1's readonly guard refuses it. **S5 and S6 are one module**, with one interface: `resolveWorker` returns the worker plus its resolved configuration, beside the create check. The PR stack is the same | BR-10–14 BR-13b BR-18 | | ||
| | S5a | `workforce` · `createWorkforceClient`, with `findWorkerSession` and `ensureWorkerSession` | A bound client: `createWorkforceClient({ userId, baseUrl?, apiPath?, fetcher? })`, the same transport options as `createSessionClient`, with the two helpers as its methods. React gets them from a hook over the same client. No ambient state and no new endpoint: the methods use the roster read and the session client. One lookup path over `listSessions({ …, state: { workerId } })`, taking one criteria object. Each criteria key maps to a readonly session-state field of the worker flow, since only readonly fields are listable (S1). FIX-1788 ships `worker`; leave the object open for later keys and define none: FIX-1794's `taskId`, FIX-1793's `workstreamId`, and FIX-1791's key for the coordinator conversation a delegate's session belongs to (FIX-1791 names it), so `ensureWorkerSession({ worker, <that key> })` gives one delegate session per coordinator conversation. A coordinator's delivery opens the delegate's session through `ensureWorkerSession` with the worker named: an action on a missing id names no worker and is refused (BR-14). Both resolve the worker's current flow from the roster first. The lookup and the derived id both include that resolved flow, not just the criteria. `find` returns the caller's most recent matching session on that flow, or none. **A match is on the key set, not only on values:** a criteria key the lookup does not name matches only sessions that do not carry that key, so `{ worker }` never returns a delegate, task or workstream session, and `{ worker, <coordinator key> }` never returns a task session. Every later key inherits this rule; no consumer restates it (epic amendment #2831). `ensure` returns what `find` returns, so with several matching sessions it is the most recent, not necessarily the derived one. Only when there is none does it create, on that flow, at an id derived (S5's function) from the caller's user, org, resolved flow and criteria. So after BR-19b's edit, `ensure` finds nothing on the new flow and creates a fresh session at a new id, and the old sessions keep refusing. It creates through the create route, which owns the 409 contract: a 409 means a racing call won, so it reads that id and returns it (the store's own create guarantee: SQLite, Postgres, one filesystem store instance) | BR-13a BR-14a BR-19b | | ||
| | S6 | `workforce` · per-turn configuration | Load the session's worker each turn; resolve tool, skill, package, capability and worker-folder names against what the installation registers; refuse a turn whose worker is fired, now names another flow, has names that don't resolve, or runs on a flow now standard-only. Every read of a worker setting moves off `ctx.flow.config` to it | BR-19–22a | |
There was a problem hiding this comment.
Implementer trap: Store listing is equality on named readonly fields. Key-set semantics (“{ worker } must not match sessions that also carry taskId / coordinator keys”) lives in Workforce per BR-14a. Worth one explicit sentence that SQL does not implement absence-of-unnamed-keys — avoids naive listSessions + sessions[0] or unbounded scans. (I’m not sure you want store-level “key absent” support later; partial criteria + derived id may be enough.)
| | BR-15 | A session is created with caller state for the link or a server-written field | Refused with 400, naming the field. Nothing written | CI · VG control `caller-link` | | ||
| | BR-16 | A session is deleted and its id created again | The new session's link is what its own create named and passed. Nothing carries over | CI | | ||
| | BR-14 | A session on a worker flow is created with no worker, by the create, by an action on a session id that doesn't exist, or by `fsdev run` without a `workerId` in `--seed-session` | Refused with 400, naming `workerId`. No session written | CI · VG leg b | | ||
| | BR-14a | Alice calls `findWorkerSession({ worker })`, or lists with `state: { workerId }` | Her sessions with that worker, most recent first for the helper; none if there are none. Never another user's. The helper matches on the key set (S5a): it returns only sessions that carry no criteria key it did not name, so plain talk never lands in a delegate, task or workstream session. The list filter is not narrowed | CI · VG leg b | |
There was a problem hiding this comment.
Same key-set note as S5a: this rule is correct but easy to implement wrong against P1’s list API. If PLAN gets a flow×lookup matrix, BR-14a could point there instead of restating semantics in the table cell.
| 3. **[D6](DECISIONS.md#d6) · On a custom worker flow, keeping one user's workers apart is the | ||
| flow's author's job.** If wrong: two of one user's workers on a custom flow read each other's | ||
| data until its author keys it by worker. Nothing crosses users. | ||
| 4. **Engine scope.** The binding ships as three engine changes beyond the epic's D3 item (3) as |
There was a problem hiding this comment.
Fourth copy of “three engine changes beyond epic D3(3).” Suggest one canonical paragraph in EVOLUTION.md#amendment-binding and a pointer here so sign-off stays PO-facing without duplicating guardrails/D5 Locks in.
| D4 -.->|"rejected · every message carries the worker"| X4["named on the first turn"] | ||
| D4 --> D5["D5 · named in a readonly field of the session's starting state"] | ||
| D5 -.->|"rejected · a second name for what state can carry"| X5["a separate server-only link"] | ||
| I --> D6["D6 · a custom worker flow's per-worker privacy is its author's"] |
There was a problem hiding this comment.
D6 vs ER-2: Substantively right (author-owned privacy on custom flows). If you want a leaner amend, D6 could be a short pointer to epic ER-2 + FIX-1789 two-shapes POC, with BR-23/BR-23a + DOCS carrying issue-specific proof — the full card + figure may be more ceremony than a post-merge documentation fix required.


The problem
The FIX-1788 spec, merged in #2812 and amended in #2818, says a session's worker sits in a separate server-only "link" field, set from a
workeroption oncreateSessionand filtered by one onlistSessions. That isn't what shipped. P1 (#2850, merged) binds a session through a readonly field of its starting state, and the product owner rejected a separate link concept. The spec also promises that every worker flow keeps each worker's data apart. On a custom worker flow, the product owner has now made that the flow's author's job. Anyone building P2 or P4 from the spec would build the wrong thing.What this does
It records three directions the product owner approved in conversation on 2026-10-07, and brings the retained spec in line with what P1 shipped and P2 (#2856, open) builds. It changes only
specs/issues/FIX-1788/. Nothing is implemented.workerIdreadonly on its session state. An app names the worker withcreateSession({ state: { workerId } })and lists by it withlistSessions({ state: { workerId } }). The server checks it once, at create, and refuses any later change on every path. A flow's create check stays optional, for rules that depend on the caller or on stored data. Only a flow that binds its sessions refuses, at create, a starting state its schema rejects. Other flows keep today's behaviour, because the mailbox and project rooms create half-filled sessions on purpose. D4's call, that the worker is named once at create, stands. Its old mechanism is kept as history.agentkeeps each worker's skills apart. On a flow someone else writes, a user's workers share that user's data, and it never crosses users. The draft docs show an author how to key data by worker.What's asked of you
The product owner approved the direction of all three on 2026-10-07. This PR records them. Review the record and merge it if it says what you meant.
<img src="
https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/061e2c4cd55efe182cdbc8e5f28b8341f73ed9c5/specs/issues/FIX-1788/figures/d5-readonly-starting-state.svg"width="940" alt="D5: what binds a session to its worker. Chosen: a readonly field of its starting state. Instead of: a separate server-only link. Decides it: one name to learn instead of two. Tie: both are checked at create. Price: the engine gains a readonly guard, a store-level filter and a binding refusal. Locks in workerId readonly on every worker flow. Flips if a binding must stay hidden from the flow's own blocks." /><img src="
https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/061e2c4cd55efe182cdbc8e5f28b8341f73ed9c5/specs/issues/FIX-1788/figures/d6-custom-flow-privacy.svg"width="940" alt="D6: on a custom worker flow, who keeps one user's workers apart. Chosen: the flow's author. Instead of: refusing at hire, or the engine partitioning. Decides it: cost to build, a docs section against a check with FIX-1789's holes or an engine change beyond the epic's six. Price: one user's workers share what the flow stores unless its author keys it. Tie: another user is never reached." />DECISIONS.md, and the engine-scope section inEVOLUTION.md.One follow-up sits outside this PR: the epic's D3 text still says "a server-only field". A separate epic amendment will take it.
A consequential rename in another issue's spec.
specs/issues/FIX-1797/PLAN.md(P3.3) named this goal's controlcaller-link; it now saysno-create-check, because this amendment replaces that control.Parts worth reviewing closely
DECISIONS.md→ D5. It replaces D4's mechanism without deleting it. D4 keeps its call and links its card as signed. The considered and dropped row on plain state (O1) stays dropped, with the answer to it.PLAN.md→ S1. It is rewritten to what P1 shipped: readonly fields, the optionalcreateCheck,serverOwned, the listing filter, the schema refusal on binding flows only, and a dispatcher's childstate.fsdev run --workeranduseFlow'sworkerare gone.SPEC.md→ the goal's control.caller-linktested a server-only field that no longer exists.no-create-checkremoves the create check, and leg b must then fail on Bob's create naming Alice's worker writes a session.BUSINESS-RULES.md→ BR-18b, andPLAN.md→ S11. Today a dispatch that reaches an existing child session adopts it after comparing identity fields, not the starting state it asked for, and the mailbox wake keys a member's conversation by mailbox alone. On oneagentcopy, two workers would share one child. P4 fixes both: the engine refuses to adopt a child whose readonly fields differ from the requestedstate, and the wake keys its child by worker too.PLAN.md→ S7. P2 removedagent's state-read partition, so its per-worker skills drawer lands in P4 through the installation's session. A partitioned skills library fails closed: a run with no partition gets an empty catalog it can't write to.Links: original review #2812 · first amendment #2818 · P1 #2850 · P2 #2856, where Q6 was asked · retained spec
specs/issues/FIX-1788/· FIX-1788 · epic FIX-1786. This merges intomainwhen the product owner merges it.How to review this
This is a post-merge amendment to a retained spec. It records directions the product owner already approved, so check the record, not the direction itself.
DOCS.md, which are reconciled at publish as before.Engineering calls
d4-named-at-create.svg, and its chosen label now reads "At create, named once", so the card and the figure agree. The signed text is linked atfcfefd47e.DOCS.mdnow points to the pages P1 published and no longer drafts them again.spec/FIX-1788-amend-1, which is the head branch of the merged spec(FIX-1788): amendment 1 · worker named at session create; fold round two #2818. This PR usesspec/FIX-1788-amend-bindingso that branch isn't pushed to.Everything else
What was read before writing.
mainatfcfefd47e:packages/engine/src/context/session-birth.ts,getReadonlyStateKeysinpackages/core/src/helpers/zod-introspect.ts,packages/core/src/types/session-create.ts, the list route's state filter inpackages/engine/src/routes/session-routes.ts, the readonly guard increateExecutionContext.tsandpackages/cli/src/commands/run.ts, the store filters (SQLite, Postgres, memory, filesystem), the dispatch birth increate-request-host.ts, and "Example: one session per project" inapps/docs/docs/fundamentals/state-and-scopes.md. P2 atc1c727fe1, and again at its current head7c765abfc:packages/workforce/src/workers/*, the skillspartitionBy,agent's drawer, the wake, the worker lookup andwriteShared.Sections changed.
SPEC.md: the before-and-after table, the goal, the goal-check table, What changes, the session diagram and the sign-off.DECISIONS.md: the intro, the tree, D4, the new D5 and D6, Decided, not asked, Considered and dropped, and How it got here.BUSINESS-RULES.md: BR-10, BR-13 to BR-16, BR-18a, the new BR-18b, BR-19 to BR-20, BR-23, the new BR-23a, BR-25a, and the acceptance criteria.PLAN.md: S1, S5, S5a, S6, S7, S11, the diagram, V1, V4, V6, VG, Pinned names, the guardrails, the sketch, At implement time and Follow-ups.DOCS.md: the shipped-names table, the P1 pointer (replacing two drafts), Talking to a worker, What is stored, Hiring the roster, the new custom-flow section, and the READMEs.EVOLUTION.md: the forward lineage and the new binding amendment.specs/issues/FIX-1797/PLAN.md: P3.3's control name only.d4-named-at-create.svg,what-changes.svg, and the newd5-readonly-starting-state.svgandd6-custom-flow-privacy.svg.Spec checks (
spec-figures.md→ Verify). Fences balanced. No risky mermaid labels. Every SVG has ext=0, one theme block, one aria-label, and 107 lines or fewer. Every nav line is present. D3 to D6 each have a trade-off figure (D1 and D2 are withdrawn, with their figures deleted earlier). No referenced figure is missing. All cross-document anchors resolve. All four changed figures were rendered in light and dark with headless Chromium and checked by eye.Process guards, run locally on this head:
validate-spec-folder,validate-no-nul-bytes,validate-model-strings,check-mailbox-rename,check-isolation-coordinate,validate-reserved-names,validate-publish-setandvalidate-changeset-refsall pass. No changeset is needed: this changes no package.Word budgets. Every document is still over its template budget, as it was before this PR. DECISIONS is 2,708 words, PLAN 3,677 and EVOLUTION 2,305.
🤖 Generated with Claude Code
https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
Generated by Claude Code